Superpowers 框架完全指南：详尽笔记

一、Superpowers 框架概述

1.1 核心定义

Superpowers 是一个基于技能（Skills）的 AI 编程代理框架，由 Jesse Vincent 开发。它通过可组合的技能和标准化工作流程，让 Claude Code、Codex 等编码助手能够像专业工程师一样思考和工作。

1.2 核心理念

让 AI 代理在写代码之前，先理解你要做什么，然后制定计划，最后才执行。

1.3 强制工作流程（6 阶段）

阶段	名称	核心动作
1	头脑风暴（Brainstorming）	理解需求，澄清模糊点
2	设计确认（Design Sign-off）	分块展示设计，等待用户确认
3	实现计划（Implementation Plan）	拆解为 2-5 分钟的小任务
4	执行开发（TDD + Subagent）	测试驱动开发，子代理执行
5	代码审查（Code Review）	每个任务完成后审查
6	分支收尾（Finish Branch）	合并/PR/清理

1.4 有无 Superpowers 的对比

维度	无 Superpowers	有 Superpowers
需求理解	直接跳进代码，不理解真实需求	先问清楚"你真正想要什么"
设计沟通	容易跑偏，需要反复纠正	设计分块确认，避免误解
任务管理	缺乏追踪	任务拆解清晰，可追踪
质量保证	缺乏测试，质量不稳定	强制 TDD，质量有保障
问题发现	后期集中暴露	自动代码审查，问题早发现

二、安装配置详解

2.1 Claude Code 安装

方式一：官方插件市场（推荐）

bash

# 启动 Claude Code
claude

# 安装插件
/plugin install superpowers@claude-plugins-official

方式二：Superpowers 市场

bash

# 先注册市场
/plugin marketplace add obra/superpowers-marketplace

# 安装插件
/plugin install superpowers@superpowers-marketplace

验证安装

重启后看到注入提示：

xml

<session-start-hook>
<EXTREMELY_IMPORTANT>
You have Superpowers.

**RIGHT NOW, go read**: @/Users/jesse/.claude/plugins/cache/Superpowers/skills/getting-started/SKILL.md
</EXTREMELY_IMPORTANT>
</session-start-hook>

更新插件

bash

/plugin update superpowers

2.2 Cursor 安装

在 Cursor Agent 聊天中：

bash

# 方式一：直接安装
/add-plugin superpowers

# 方式二：在市场搜索 "superpowers"

2.3 Codex（OpenAI）安装

步骤 1：克隆仓库

bash

git clone https://github.com/obra/superpowers.git ~/.codex/superpowers

步骤 2：创建技能符号链接

bash

# 创建技能目录
mkdir -p ~/.agents/skills

# 创建符号链接
ln -s ~/.codex/superpowers/skills ~/.agents/skills/superpowers

Windows 用户（使用 Junction）

powershell

# 创建目录
New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.agents\skills"

# 创建 Junction（不需要开发者模式）
cmd /c mklink /J "$env:USERPROFILE\.agents\skills\superpowers" "$env:USERPROFILE\.codex\superpowers\skills"

步骤 3：配置多代理支持（可选）

toml

# ~/.codex/config.toml
[features]
multi_agent = true

步骤 4：重启并验证

bash

# 重启后询问
Tell me about your superpowers

更新技能

bash

cd ~/.codex/superpowers && git pull

卸载

bash

# 删除符号链接
rm ~/.agents/skills/superpowers

# 可选：删除克隆的仓库
rm -rf ~/.codex/superpowers

2.4 OpenCode 安装

步骤 1：修改配置文件

在全局或项目级的 opencode.json 中添加：

json

{
  "plugin": ["superpowers@git+https://github.com/obra/superpowers.git"]
}

步骤 2：指定版本（可选）

json

{
  "plugin": ["superpowers@git+https://github.com/obra/superpowers.git#v5.0.3"]
}

步骤 3：重启 OpenCode

插件自动通过 Bun 安装并注册所有技能。

验证

bash

Tell me about your superpowers

使用技能工具

bash

use skill tool to list skills
use skill tool to load superpowers/brainstorming

清理旧安装

bash

# 删除旧符号链接
rm -f ~/.config/opencode/plugins/superpowers.js
rm -rf ~/.config/opencode/skills/superpowers

# 可选：删除克隆的仓库
rm -rf ~/.config/opencode/superpowers

# 从 opencode.json 移除 skills.paths 配置

2.5 Gemini CLI 安装

bash

# 安装扩展
gemini extensions install https://github.com/obra/superpowers

# 更新扩展
gemini extensions update superpowers

三、核心技能系统详解

3.1 技能的本质

每个技能是一个包含 SKILL.md 文件的目录，定义：

触发条件（什么时候使用这个技能）
执行步骤（具体怎么做）
输出规范（应该产生什么结果）

技能是强制性的，不是建议。当条件匹配时，AI 必须使用对应的技能。

3.2 设计与规划类技能

`brainstorming` – 头脑风暴

属性	说明
触发时机	开始写代码之前
核心功能	通过提问澄清模糊需求；探索多种实现方案；分块展示设计，等待用户确认；保存设计文档

示例对话结构：

用户：我想做一个待办事项应用

AI（触发 brainstorming）：
好的，让我先了解一些细节：

1. 这个应用是 Web 端、移动端还是桌面端？
2. 需要用户登录吗？数据存在哪里？
3. 需要哪些核心功能？（增删改查、分类、提醒...）
4. 有技术栈偏好吗？
5. 预计用户规模？

我们先花 5 分钟把需求理清楚，再开始设计。

`writing-plans` – 编写实现计划

属性	说明
触发时机	设计确认后
核心功能	将工作拆解为 2-5 分钟的小任务；每个任务包含精确文件路径、完整代码、验证步骤；强调 YAGNI 和 DRY 原则

计划示例结构：

markdown

## 任务 1：项目初始化
- 文件：`package.json`, `tsconfig.json`
- 步骤：
  1. 创建 package.json，配置 dependencies
  2. 创建 tsconfig.json，启用严格模式
- 验证：`npm install` 无错误

## 任务 2：数据库 Schema
- 文件：`src/db/schema.ts`
- 步骤：
  1. 定义 Todo 接口
  2. 创建 SQLite 表结构
- 验证：运行迁移脚本

3.3 开发与执行类技能

`using-git-worktrees` – 使用 Git 工作树

属性	说明
触发时机	设计批准后，开始实现前
核心功能	在新分支上创建隔离的工作区；运行项目初始化；验证测试基线干净
优势	支持并行开发多个功能；不会互相干扰；易于清理和回滚

`subagent-driven-development` – 子代理驱动开发

属性	说明
触发时机	计划确认后
核心功能	为每个任务分配 fresh subagent；两阶段审查（规范合规性 → 代码质量）；自动继续下一个任务

工作流程：

主代理 → 分派任务 1 → Subagent A → 完成 → 审查 → ✓
       → 分派任务 2 → Subagent B → 完成 → 审查 → ✓
       → 分派任务 3 → Subagent C → 完成 → 审查 → ✗ 修复
       → ...

`test-driven-development` – 测试驱动开发

属性	说明
触发时机	实现过程中
核心功能	强制 RED-GREEN-REFACTOR 循环；写失败测试 → 看它失败 → 写最少代码 → 看它通过 → 提交；删除测试前写的代码

核心原则：

1. 先写测试（RED）
2. 运行测试，确认失败
3. 写刚好能让测试通过的代码（GREEN）
4. 运行测试，确认通过
5. 重构代码（REFACTOR）
6. 提交

`executing-plans` – 执行计划

属性	说明
触发时机	有计划，但不使用子代理时
核心功能	批量执行任务；在关键点设置人工检查点；适合小型任务或快速迭代

3.4 审查与收尾类技能

`requesting-code-review` – 请求代码审查

属性	说明
触发时机	任务完成后
核心功能	对照计划审查代码；按严重程度报告问题；关键问题阻止进度

审查清单：

代码符合设计规范吗？
测试覆盖充分吗？
有安全漏洞吗？
性能可接受吗？
代码可读吗？

`finishing-a-development-branch` – 完成开发分支

属性	说明
触发时机	所有任务完成后
核心功能	验证所有测试通过；提供选项（合并/PR/保留/丢弃）；清理工作树

3.5 调试类技能

`systematic-debugging` – 系统化调试

属性	说明
触发时机	遇到 bug 时
核心功能	4 阶段根因分析流程；根因追踪技术；防御性编程；条件等待技术

调试流程：

1. 复现问题 → 最小化复现步骤
2. 定位根因 → 二分查找、日志分析
3. 设计修复 → 考虑边界情况
4. 验证修复 → 确保真的修好了

`verification-before-completion` – 完成前验证

属性	说明
触发时机	声称修复 bug 后
核心功能	确保问题真的解决了；防止"看起来修好了"的假阳性

3.6 协作类技能

技能名称	触发时机	核心功能
`dispatching-parallel-agents`	需要并发处理多个任务时	同时启动多个子代理；协调结果合并；适合独立任务
`receiving-code-review`	收到审查反馈时	如何回应审查意见；优先级处理（Critical → Major → Minor）；讨论和协商技巧

3.7 元技能

技能名称	触发时机	核心功能
`writing-skills`	需要创建新技能时	技能创建最佳实践；技能测试方法；技能文档规范
`using-superpowers`	新会话开始	介绍技能系统；如何查找和使用技能；技能使用纪律

四、核心原则体系

4.1 四大核心原则

原则	核心表述	实践要点
测试驱动开发（TDD）	写测试优先，永远	测试是规格说明；测试是安全网；测试是设计工具
系统化胜过临时发挥	流程胜过猜测	遵循既定流程；不要跳过步骤；每一步都有明确目标
复杂度降低	简单性是首要目标	YAGNI：你不会需要它；DRY：不要重复自己；KISS：保持简单
证据胜过声明	验证后再宣布成功	不要说"应该修好了"；要说"测试通过了"；用数据说话

五、实战示例分析

5.1 示例 1：Claude Code 开发用户登录功能

完整流程时间线：

启动 Claude Code
    ↓
用户输入需求："我想给项目添加用户登录功能"
    ↓
[自动触发 brainstorming]
    ↓
AI 提问澄清（5个关键问题）
    ↓
用户回答具体需求
    ↓
[触发 using-git-worktrees]
    ↓
创建隔离 worktree，验证测试基线
    ↓
AI 展示实现计划（5个任务）
    ↓
用户确认
    ↓
[触发 subagent-driven-development]
    ↓
分派子代理并行/串行执行任务
    ↓
每个任务完成后自动代码审查
    ↓
[2小时后] 所有任务完成，测试通过率 92%
    ↓
提供分支收尾选项（PR/合并/保留/丢弃）

5.2 示例 2：Codex 调试生产环境故障

完整流程时间线：

启动 Codex
    ↓
用户报告："生产环境认证服务挂了"
    ↓
[自动触发 systematic-debugging]
    ↓
阶段 1：复现问题（4个关键问题）
    ↓
用户回答故障现象
    ↓
[触发 verification-before-completion]
    ↓
AI 分析日志，定位根因
    ↓
提出临时修复 + 永久修复方案
    ↓
用户授权先恢复服务
    ↓
执行临时修复，验证恢复
    ↓
执行永久修复（启动脚本）
    ↓
添加健康检查端点
    ↓
提供后续建议（监控、告警、密钥管理）

六、自定义技能开发

6.1 技能目录结构

~/.agents/skills/my-skill/
├── SKILL.md          # 必需：技能定义
├── references/       # 可选：参考资料
│   └── example.md
└── scripts/          # 可选：辅助脚本
    └── run.sh

6.2 SKILL.md 标准格式

markdown

---
name: my-custom-skill
description: 当 [条件] 时使用 - [做什么]
---

# 技能名称

## 触发条件

[描述什么时候应该使用这个技能]

## 执行步骤

1. 第一步
2. 第二步
3. ...

## 输出规范

[应该产生什么结果]

## 注意事项

- 安全提示
- 边界情况
- 常见错误

6.3 示例：代码格式化技能

markdown

---
name: format-code
description: 当代码提交前或审查时发现格式问题 - 自动格式化代码
---

# 代码格式化技能

## 触发条件

- 用户请求格式化代码
- 代码审查发现格式不一致
- 提交前自动检查

## 执行步骤

1. 检测项目使用的格式化工具：
   - 查找 `.prettierrc`、`.eslintrc` 等配置文件
   - 检查 `package.json` 中的格式化脚本

2. 安装依赖（如果需要）：
   ```bash
   npm install --save-dev prettier eslint

运行格式化：

bash

npm run format
# 或 npx prettier --write .

验证格式化结果：
- 运行 linter 检查
- 确认没有引入功能变更

提交格式化变更（单独提交）：

bash

git add -A
git commit -m "chore: auto-format code"

输出规范

格式化后的代码
格式化报告（修改了哪些文件）
单独的 git 提交

注意事项

格式化提交应该与功能提交分开
不要在一次提交中混合功能变更和格式化
大项目可能需要分批次格式化


---

## 七、故障排查指南

### 7.1 技能没有触发

| 可能原因 | 解决方法 |
|:---|:---|
| 技能描述不够清晰 | 优化 `description` 字段 |
| 触发条件不匹配 | 检查用户输入是否符合触发条件 |
| 技能未被正确加载 | 按平台检查加载状态 |

**各平台检查命令：**

```bash
# Claude Code: 检查插件状态
/plugin list

# Codex: 检查符号链接
ls -la ~/.agents/skills/superpowers

# OpenCode: 检查插件加载
opencode run --print-logs "hello" 2>&1 | grep -i superpowers

7.2 技能执行失败

可能原因	解决方法
缺少依赖（二进制、环境变量）	检查技能的前置条件
权限问题	手动执行技能中的命令验证
技能逻辑错误	查看 AI 的错误输出

7.3 更新后技能不工作

bash

# Claude Code
/plugin update superpowers

# Codex
cd ~/.codex/superpowers && git pull

# OpenCode
# 重启 OpenCode，插件会自动更新

# 全部不行：卸载重装

八、最佳实践总结

8.1 使用建议（5条）

序号	建议	说明
1	让流程自然发生	不要强制跳过步骤
2	认真阅读设计	AI 会分块展示，每块都要确认
3	信任 TDD	即使看起来慢，长期来看更快
4	利用子代理	复杂任务分派出去，主代理做协调
5	审查每个任务	不要等到最后才审查

8.2 不适合的场景

场景	原因
快速原型	直接写代码更快
简单修改	一两行代码的改动
探索性编程	还不知道要做什么

8.3 性能优化策略

场景	策略
大项目	使用 worktrees 并行开发
复杂功能	拆分成多个小计划
紧急修复	可以跳过部分流程，但要事后补上测试

九、社区与资源

9.1 官方资源

资源类型	链接
GitHub	https://github.com/obra/superpowers
博客	https://blog.fsck.com/2025/10/09/superpowers/
Discord	https://discord.gg/Jd8Vphy9jq
问题追踪	https://github.com/obra/superpowers/issues

9.2 相关资源

资源	链接
AgentSkills 规范	https://agentskills.io
Microsoft Amplifier	https://github.com/microsoft/amplifier
Cialdini 影响力研究	https://gail.wharton.upenn.edu/research-and-insights/call-me-a-jerk-persuading-ai/

9.3 贡献技能流程

Fork 仓库
创建技能分支
遵循 writing-skills 技能创建和测试
提交 PR

十、总结评价

10.1 框架价值

Superpowers 是一个革命性的 AI 编程框架，它让编码代理能够：

能力	实现方式
先理解，后实现	brainstorming + design sign-off
测试驱动	TDD 技能强制 RED-GREEN-REFACTOR
任务拆解	writing-plans 拆解为 2-5 分钟任务
自动审查	requesting-code-review 每个任务后审查
可扩展	自定义技能满足特定需求

10.2 适用人群

用 AI 进行严肃软件开发的人
需要 AI 遵循工程最佳实践的团队
希望 AI 更可靠、更可预测的用户

10.3 下一步行动建议

根据你的平台安装 Superpowers
尝试一个小型项目，体验完整流程
阅读 getting-started 技能深入了解
考虑贡献你自己的技能到社区

参考资料版本：本文基于 Superpowers v5.x 编写，安装方式可能随版本更新而变化。请参考官方文档获取最新信息。

Superpowers 框架完全指南：详尽笔记 ​

一、Superpowers 框架概述 ​

1.1 核心定义 ​

1.2 核心理念 ​

1.3 强制工作流程（6 阶段） ​

1.4 有无 Superpowers 的对比 ​

二、安装配置详解 ​

2.1 Claude Code 安装 ​

2.2 Cursor 安装 ​

2.3 Codex（OpenAI）安装 ​

2.4 OpenCode 安装 ​

2.5 Gemini CLI 安装 ​

三、核心技能系统详解 ​

3.1 技能的本质 ​

3.2 设计与规划类技能 ​

brainstorming – 头脑风暴 ​

writing-plans – 编写实现计划 ​

3.3 开发与执行类技能 ​

using-git-worktrees – 使用 Git 工作树 ​

subagent-driven-development – 子代理驱动开发 ​

test-driven-development – 测试驱动开发 ​

executing-plans – 执行计划 ​

3.4 审查与收尾类技能 ​

requesting-code-review – 请求代码审查 ​

finishing-a-development-branch – 完成开发分支 ​

3.5 调试类技能 ​

systematic-debugging – 系统化调试 ​

verification-before-completion – 完成前验证 ​

3.6 协作类技能 ​

3.7 元技能 ​

四、核心原则体系 ​

4.1 四大核心原则 ​

五、实战示例分析 ​

5.1 示例 1：Claude Code 开发用户登录功能 ​

5.2 示例 2：Codex 调试生产环境故障 ​

六、自定义技能开发 ​

6.1 技能目录结构 ​

6.2 SKILL.md 标准格式 ​

6.3 示例：代码格式化技能 ​

输出规范 ​

注意事项 ​

7.2 技能执行失败 ​

7.3 更新后技能不工作 ​

八、最佳实践总结 ​

8.1 使用建议（5条） ​

8.2 不适合的场景 ​

8.3 性能优化策略 ​

九、社区与资源 ​

9.1 官方资源 ​

9.2 相关资源 ​

9.3 贡献技能流程 ​

十、总结评价 ​

10.1 框架价值 ​

10.2 适用人群 ​

10.3 下一步行动建议 ​

Superpowers 框架完全指南：详尽笔记

一、Superpowers 框架概述

1.1 核心定义

1.2 核心理念

1.3 强制工作流程（6 阶段）

1.4 有无 Superpowers 的对比

二、安装配置详解

2.1 Claude Code 安装

2.2 Cursor 安装

2.3 Codex（OpenAI）安装

2.4 OpenCode 安装

2.5 Gemini CLI 安装

三、核心技能系统详解

3.1 技能的本质

3.2 设计与规划类技能

`brainstorming` – 头脑风暴

`writing-plans` – 编写实现计划

3.3 开发与执行类技能

`using-git-worktrees` – 使用 Git 工作树

`subagent-driven-development` – 子代理驱动开发

`test-driven-development` – 测试驱动开发

`executing-plans` – 执行计划

3.4 审查与收尾类技能

`requesting-code-review` – 请求代码审查

`finishing-a-development-branch` – 完成开发分支

3.5 调试类技能

`systematic-debugging` – 系统化调试

`verification-before-completion` – 完成前验证

3.6 协作类技能

3.7 元技能

四、核心原则体系

4.1 四大核心原则

五、实战示例分析

5.1 示例 1：Claude Code 开发用户登录功能

5.2 示例 2：Codex 调试生产环境故障

六、自定义技能开发

6.1 技能目录结构

6.2 SKILL.md 标准格式

6.3 示例：代码格式化技能

输出规范

注意事项

7.2 技能执行失败

7.3 更新后技能不工作

八、最佳实践总结

8.1 使用建议（5条）

8.2 不适合的场景

8.3 性能优化策略

九、社区与资源

9.1 官方资源

9.2 相关资源

9.3 贡献技能流程

十、总结评价

10.1 框架价值

10.2 适用人群

10.3 下一步行动建议